﻿/*!
 * Copyright (c), 上海沃恩信息科技有限公司.
 * All rights reserved.
 * Licensed under BSD (https://www.pittypat.work/bsd.html).
 */

using System;
using System.Threading;
using System.Threading.Tasks;

namespace Pittypat
{
    /// <summary>
    /// 在异步操作过程中报告异步操作的进度。WebSocket 等使用此接口向客户端报告操作进度，以便能够向用户显示一个进度条。
    /// </summary>
    /// <remarks>
    /// IAsyncProgress 中已经包含了类型为 CancellationToken 的 <see cref="Token"/> 属性，因为进行异步操作时不再需要额外传递 CancellationToken 类型的值。
    /// </remarks>
    public interface IAsyncProgress : IDisposable
    {
        /// <summary>
        /// 获取用于取消异步操作的标记。
        /// </summary>
        CancellationToken Token { get; }

        /// <summary>
        /// 汇报异步操作的进度。
        /// </summary>
        /// <param name="percent">当前进度的百分比，从 0 到 100，达到 100 时认为操作完成。</param>
        /// <param name="message">当前进度下的消息。</param>
        /// <param name="value">同时发送给远程终端的值。通常在操作完成时向远程客户端返回操作结果。</param>
        /// <returns>异步任务。</returns>
        /// <remarks>
        /// 百分比、消息和值都会被发送给远程终端。百分比可以用于创建进度条，消息则用于在操作过程中向用户显示友好的信息。
        /// </remarks>
        Task ReportAsync(float percent, string message, IJson value = null);
    }
}
